RtkIPC

NOTE: The RtkIPC sample does not work with Visual Studio 2017, as the WDK is not yet compatible with that version of Visual Studio. The Visual Studio 2017-specific files associated with this sample are not installed with the RTX64 SDK.

Description

This sample demonstrates usage of the Real-Time Kernel (RTK) API and how to synchronize a Windows driver with a RTX64 process. The RTK API is analogous to the existing RTX64 Real-Time (RT) API Inter-process communication (IPC) calls used within a Windows user mode application, but can be used by Windows kernel drivers. This example will demonstrate how to set up a Windows kernel driver so that it can access RTSS mutexes, events, semaphores, and shared memory.

This sample contains 3 projects:

• RtkIPCDrv – a RTX64 RTK API-enabled Windows kernel mode driver. This driver sets up 4 threads, each set up to use mutex, event, semaphore and shared memory objects for inter-process communication. Each thread performs inter-process communication via shared memory and also performs mutex, event or semaphore based synchronizations to parse the shared memory contents.
• RtkRtssApp – a RTX64 RTSS application used to communicate with the Windows driver RtkIPCDrv through inter-process communication mechanisms using shared memory and mutex, event or semaphore synchronization objects.
• RTkIPCApp – a Windows console application that interfaces with the RTK enabled kernel mode driver.

Source Files

RtkIPCDrv.sys is composed of the following source files:

• RtkIPCDrv.c is the main source code for this sample. It contains DriverEntry, which sets up threads to perform inter-process communication.
• Thread.c is the source code that contains implementation of various thread handlers using RTKAPI to perform inter-process communication.

RtkRtssApp.rtss is composed of the following source files:

• RtkIPCDrv.c is the source code that contains usage of RTAPI functions similar to what the RTKAPI functions use to perform Windows driver inter-process communication.

RtkIPCApp.exe is composed of the following source files:

• RtkIPCDrv.c is a Windows console application that interfaces with RtkIpcDrv.sys and controls the startup and shutdown of the driver.

Instructions for Building and Setting up the RtkAPI Sample

NOTE: These steps require Visual Studio 2015 and Windows Driver Kit (WDK) 10.

1. Install Visual Studio 2015. When installing, select the Tools for Windows 10 Universal Apps (Windows SDK 10.0.10240) feature.
2. Install WDK 10.
3. Launch Visual Studio 2015 and open the RtkIPC sample solution, RtkIPC_VS2015.sln.
4. Build the RtkIPCDrv.sys binary.
1. Verify that RtkIPCDrv.sys was built without any errors.
2. In order to load RtkIPCDrv.sys, make sure it is signed or disable signing.
3. Install the driver using InstallDriver.bat.

NOTE: The target Operating System version is set as Windows 7 (in Driver Settings). As a result, RtkIPCDrv.sys will run on all Windows versions supported by RTX64 (7, 8, 8.1, and 10).

5. Build RtkRtssApp.rtss
6. Build RtkWinApp.exe

NOTE: If you encounter errors relating to headers and libs while building RTK drivers, ensure that the installed versions of the WDK and Windows SDK match, and also ensure that the Target Platform Version setting in Visual Studio 2015 (Configuration Properties > General > Target Platform Version) is set to the correct version number.

Running RtkAPISample

1. Start the Subsystem. You can do this directly from the RTX64 Control Panel.
2. Launch a Command Prompt as Administrator and navigate to the RtkIpcSample folder.
3. Type ”RunWinApp start” to load RtkIpcDrv.sys.
4. Run the test by issuing the following commands:
1. To test mutex access, type “RunWinApp mutex”
2. To test event access, type “RunWinApp event”
3. To test semaphore access, type “RunWinApp semaphore”
4. To test shared memory, type "RunWinApp shmem"
5. Depending on the type of test you are running, you should see feedback from both the Windows driver and RtkRtssApp.rtss.
6. After the test is complete, you may unload the Windows driver by typing “RunWinApp stop”.

IMPORTANT! Stopping the subsystem is not sufficient to unload the driver. The driver requires the subsystem to be running in order to completely stop itself. The subsystem cannot be reloaded until it is completely unloaded. For this reason, step 6 must be completed before the subsystem is stopped or else a restart will be required before the subsystem can be started again.

APIs Referenced

RTKAPI

RtkCloseHandle RtkCreateEvent RtkCreateMutex RtkCreateSharedMemory RtkReleaseMutex RtkReleaseSemaphore RtkRtssAttach RtkRtssAttachEx RtkRtssDetach RtkSetEvent RtkWaitForSingleObject

See Also

Windows Driver IPC API (RTKAPI) Overview